\documentclass[12pt]{article}

\usepackage{graphicx}

\title { eJourn Development Guide }
\author {Chris Hilton }


\begin{document}

\maketitle
\tableofcontents


\section {Introduction}

\subsection {Purpose - For this document}

To acquaint developers with writing plugins and extending/modifying eJourn.

\subsection {Where to start?}

I recommend you start with the information on what functions go in a plugin, and how to build the plugin.  You will probably end up reading this document in its entirety before you finish your plugin, but I doubt you will benefit from reading it all up front.

\section {File Format}

\subsection {The Rules}
\begin{itemize}
    \item The system is tag based, ie "$<$tag$>$" and "$<$/tag$>$"
    \item Tags do not allow for attributes, only static names.
    \item Immediately following a tag, open or close, can be another tag, or data.
    \item Data must be immediately followed by a corresponding close tag.
    \item Data may not follow a close tag
    \item The characters '$<$' and '$>$' and backslash will be escaped by a backslash. 
\end{itemize}

\newpage

\subsection {The Result}

\begin {tabbing}
$<$meta\=$>$\\
\>	$<$file \=data$>$\\
\>\>		$<$encryption type$>$AES256$<$/encryption type$>$\\
\>\>		$<$media \=type$>$Native$<$/media type$>$\\
\>	$<$/file data$>$\\
\>	$<$timestamps$>$\\
\>\>		$<$created$>$Time here, stringMatch$<$/created$>$\\
\>\>		$<$last-edit$>$time here, it will be in a string$<$/last-edit$>$\\
\>	$<$/timestamps$>$\\
\>	$<$info$>$\\
\>\>		$<$weather$>$probably a number$<$/weather$>$\\
\>\>		$<$mood$>$probably a number$<$/mood$>$\\
\>	$<$/info$>$\\
\>	$<$subject$>$this is like an entry title$<$/subject$>$\\
\>	$<$links$>$\\
\>\>		$<$lnk$>$\\
\>\>\>			$<$href$>$what to do goes here$<$/href$>$\\
\>\>\>			$<$name$>$what to say to the user goes here$<$/name$>$\\
\>\>		$<$/lnk$>$\\
\>\>		$<$lnk$>$\\
\>\>\>			$<$href$>$another what to do$<$/href$>$\\
\>\>\>			$<$name$>$another what to say$<$/name$>$\\
\>\>\		$<$/lnk$>$\\
\>	$<$/links$>$\\
\>	$<$attachments$>$\\
\>\>		$<$atchmnt$>$\\
\>\>\>			$<$name$>$a name, like "doggy.jpg"$<$/name$>$\\
\>\>\>			$<$location$>$\/attch\/doggy.jpg$<$/location$>$\\
\>\>		$<$/atchmnt$>$\\
\>\>		$<$atchmnt$>$\\
\>\>\>			$<$name$>$a name, like "kitty.jpg"$<$/name$>$\\
\>\>\>			$<$location$>$\/attch\/kitty.jpg$<$/location$>$\\
\>\>		$<$/atchmnt$>$\\
\>	$<$/attachments$>$\\
$<$/meta$>$
\end{tabbing}


\subsection {Commentary}

You'll notice the markup looks somewhat like xml/sgml.  However, there are major differences, and it's unlikely that an xml parser will work correctly with it.  You may be able to add a simple wrapper to an xml parser which does the escape sequencing and doesn't allow you to set attributes.

Otherwise, a parser for the format is well under a thousand lines of c code.

You should note that when you generate a dictionary from this file format the names of each item will correspond exactly with the tag names, except without the brackets.  And visa-versa.

\section {Library}

This section will include useful functions within libejourn.so that you'll probably want to use.

\subsection {dict.h}

This is the file with functions for dictionary objects.  You'll likely make very heavy use of these functions and should know the behaviour well.

The objects basically track key:object pairs.  They also track the type for each key, however your choices for type are limited too:
\begin {itemize}
\item DICT\_TYPE\_LST - See list.h for this type
\item DICT\_TYPE\_INT - This is an integer
\item DICT\_TYPE\_STR - This is a c string
\item DICT\_TYPE\_DCT - This is another dictionary object
\item DICT\_TYPE\_OBJ - This is a generic object, any human readable transforms (print, xmltodict) are disabled for these types unless you provide your own methods.

\end {itemize}

\subsubsection {dict\_get (struct dict *dct, const char *name)}

This function returns the value associated with key name, or NULL if no value is found.

It is recommended when using this to try and grab things in the order in which they were added.  The dictionaries do not sort internally, instead they search from your last request and just add items in sequential order.  So, if the key you ask for now is next to the last key you asked for it will only have to check two key's to find yours (or possibly three).

The search goes as such:  Check current key, check previous key, check next key.  It then moves out to the previous of the previous and the next of the next and so on.


\subsubsection {dict\_set (struct dict *dct, const char *name, void *value)}

This function works much like dict\_get(...) except that instead of returning the value for key it sets it to value.  If there is no key name yet it will create one.

It defaults to type DICT\_TYPE\_STR as this will be the most common type entered.  And it defaults to not free the object.


\subsubsection {dict\_set\_type(struct dict *dct, const char *name, int type)}

This function sets the type for the key name.  If this key doesn't exist the behaviour is unknown.  You should only do it if you know this key is there, presumably because you just called dict\_set(...).

\subsubsection {dict\_set\_free(struct dict *dct, const char *name, int free)}

This function sets the free ownership for the key name.  If this key doesn't exist the behaviour is unknown.  You should only do it if you know this key is there, presumably because you just called dict\_set(...).

If free is 0 the dict object will not free it when the time comes.  If it is 1 then it will:  So essentially setting free to 1 implies that this dict object owns the value it has for the key name.

If the object is of type DICT\_TYPE\_LSt or DICT\_TYPE\_DCT then this is moot as it uses reference counting for them.


\subsubsection {dict\_get\_list(struct dict *dct, const char *name)}

This returns the value for key name, but it makes sure that what's returned will be of type struct list.  This means that if you expect a list, but there may have only been one item and so it may have been interpretted as a dict then you can be sure, by using this function, you will get a list:  Even if it's a list of length 1.

If the value for key name was already a list it is simply returned.

\subsubsection {dict\_check(struct dict *dct, ...)}

This function takes a list of c strings which are key names.  It checks if all of these names exist inside of itself and returns 1 if it cannot find one of them or 0 if it finds all of them.

This is a handy way to make sure, in a couple lines, that all the calls in your function aren't going to get NULL back, this is what it insures.  So, if you set a key to NULL and check it you will get 1!

The list is NULL terminated.

Example:\\
$if (dict\_check(dct, "HELLO", "WORLD", NULL)) \{ printf("Oops, bad dict\\n") ; return; \}$

\subsection {xmldict.h}

   This module allows for translation between the in memory dict objects and
   the disk saveable "xml" documents.
   This should provide a very convenient, and reasonably efficient, method
   for savind and reading your own files for config and for saving user data.

\subsubsection {struct dict *elog\_xml\_to\_dict(const char *xml) }

This converts an xml represented string (as documented in the file format) to a dict object.

\subsubsection {char *elog\_dict\_to\_xml(struct dict *dct, const char *meta)}

This converts a dict object to an xml formatted string (as documented in the file format).  The output is not in "pretty" format, so there will be no whitespace in it.  You can use elog\_xml\_readify(...) in xml.h to alleviate this issue.


\subsection {tab.h}

\subsection {list.h}

My fingers are tired now...

\section {Plugin Writing}

This section describes the points where you can plugin behaviour to eJourn and how to build these plugins.

One thing you should remember is that all functions, or plugin points, are optional (with some noted exceptions).  This means that if you don't want to do anything at that point you should simply not write that function.  There is a slight performance penalty just for calling your function when it does nothing, and it may be higher for different functions, so if you're not going to do anything just don't include the function.

\subsection {An Example}

--This will be filled in when a good example exists.--

\subsection {Building Your Plugin}

Build options go here..

\subsection {Explaining Each Function}

Every function has the same arguments:\\
(struct dict *static, struct dict *instance, struct dict *input)

These arguments are as follows:
\begin {itemize}

\item static - This argument represents the information for the plugin statically.  Think of this like static class data.  Multiple instances of the code in your plugin will get this same dictionary object.

\item instance - This dictionary is passed into each function in your instance.  So, it would be wise to store things like your widgets here if you need to reference them.  If there are multiple uses of your plugin code then they will each get their own instance dictionary object.

\item input - This is the input from the eJourn program for this specific function call.  So, if it were an \_\_\_open you'd probably get one member that contained the document which was opened.  This may be used for output as well:  You may be contractually expected to put things into this dictionary object in your function call.

\end{itemize}


\newpage
\subsubsection {\_\_\_init}

This function is called when the plugin is loaded.  This function is required even if your plugin does nothing.

The input dictionary for this will contain:
\begin {itemize}

\item Nothing yet.

\end {itemize}

\newpage
\subsubsection {\_\_\_ugly}

This is called when the program closes.  The idea is that you shouldn't bother cleaning up any resources the OS can clean up:  Such as memory.  You should do what you must, quickly (and remember the system will have already called your save call).

An example is saving configuration data.

There is no input for this method.

\newpage
\subsubsection {\_\_\_end}

This is called when your plugin is closed.  Presumably the user has removed your plugin from the program.  So you need to clean up everything:  Remove any widgets, cleanup memory, save any opened files, save configuration, and you can probably note to yourself some sadness as this user doesn't want to use your code anymore ;).

There is no input for this method.


\newpage
\subsubsection {\_\_\_open}

The input dictionary for this will contain:
\begin {itemize}

\item "doc" - This is the document which eJourn opened.  Please don't make changes to it.

\end {itemize}

The open method doesn't expect any changes to its input dictionary.

\newpage
\subsubsection {\_\_\_save}

The input dictionary for this will contain:
\begin {itemize}

\item "doc" - This is the document eJourn will be saving.  Please fill in whatever of this document that your plugin knows about.

\end {itemize}


\newpage
\subsection {Special Functions}

The world is never right, it seems, without exceptions.  There are some older functions that had special purposes which we keep for simplicity of code and because why change them, they're easy.

These functions are required simply because they're used by the program to display things about your plugin to the user without actually, formally, loading your plugin.  It's sort of a short load, check, remove cycle for each plugin to get this base information.  This is also why their behaviour is different.

They all take no arguments.

\subsubsection {\_\_\_info}

This function is the string users see describing your plugin.  This function is required.  You might want to do something like this:

$char *\_\_\_info() \{  return "This plugin is an example and does nothing";  \}$ 


\subsubsection {\_\_\_author}

This function says who wrote your plugin.  It's required.  Do something like this:

$char *\_\_\_author() \{  return "Chris <MA_D> Hilton";  \}$ 


\newpage

\section {LICENSE}
This document is licensed under the GNU Free Documentation License.  eJourn code is licensed under the GNU General Public License version 2.

\subsection {AUTHORSHIP}

Initial writer, Chris $<$MA\_D$>$ Hilton

\end{document}

